<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN">
<html>
<head>
<title>DRV_MEMORY_AsyncRead Function</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="generator" content="Doc-O-Matic" />
    <meta http-equiv="Content-Style-Type" content="text/css" />
    <link rel="STYLESHEET" href="default.css" type="text/css" />

<script type="text/javascript" src="scripts.js"></script>
</head>
<body class="Element700" onload="onBodyLoadEx('frames.html', 'topic', '00303.html');" onmousedown="onBodyMouseDown();">

<!-- Begin Popups -->

<!-- End Popups -->

<!-- Begin Page Header -->
<div class="Element710" id="areafixed">
<div class="Element94">
<a href="00007.html" target="topic">Driver Libraries Help</a> &gt; <a href="00071.html" target="topic">Memory Driver Library Help</a> &gt; <a href="00072.html" target="topic">Library Interface</a> &gt; c) Block Operation Functions &gt; <a href="00303.html" target="topic">DRV_MEMORY_AsyncRead Function</a></div>
<div class="Element92">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element1">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element2">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element90">
<a href="00302.html" target="topic">Previous</a> | <a href="00072.html" target="topic">Up</a> | <a href="00304.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element96">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: DRV_MEMORY_AsyncRead@DRV_HANDLE@DRV_MEMORY_COMMAND_HANDLE *@void *@uint32_t@uint32_t Topic Title: DRV_MEMORY_AsyncRead Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table><div class="Element5">
DRV_MEMORY_AsyncRead Function</div>
</div>
</div>

<!-- End Page Header -->

<!-- Begin Client Area -->
<div class="Element720" id="areascroll">
<div class="Element721">

<!-- Begin Page Content -->
<a name="PageContent"></a><div class="Element58">
<a name="4465736372697074696F6E"></a><div class="Element11">
<div class="Element10">
<p class="Element10">
This function schedules a non-blocking read operation for reading blocks of data from the memory device attached.&nbsp;</p>
<p class="Element10">
The function returns with a valid command handle in the commandHandle argument if the request was scheduled successfully.&nbsp;</p>
<p class="Element10">
The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified.&nbsp;</p>
<p class="Element10">
The function returns <a href="00307.html" target="topic">DRV_MEMORY_COMMAND_HANDLE_INVALID</a> in the commandHandle argument under the following circumstances:</p>
<ul class="Element630">
<li class="Element600">if a buffer object could not be allocated to the request</li>
<li class="Element600">if the target buffer pointer is NULL</li>
<li class="Element600">if the client opened the driver for write only</li>
<li class="Element600">if the number of blocks to be read is either zero or more than the number of blocks actually available</li>
<li class="Element600">if the driver handle is invalid</li>
</ul></div>
</div>
<a name="43"></a><div class="Element99">
C</div>
<div class="Element101"><div class="Element100"><pre class="Element100"><strong><span style="color: #000080">void</span></strong> <strong><span style="color: #000000">DRV_MEMORY_AsyncRead</span></strong>(
    <strong><span style="color: #000080">const</span></strong> <a href="00257.html" target="topic">DRV_HANDLE</a> <strong><span style="color: #000000">handle</span></strong>, 
    <a href="00306.html" target="topic">DRV_MEMORY_COMMAND_HANDLE</a> * <strong><span style="color: #000000">commandHandle</span></strong>, 
    <strong><span style="color: #000080">void</span></strong> * <strong><span style="color: #000000">targetBuffer</span></strong>, 
    uint32_t <strong><span style="color: #000000">blockStart</span></strong>, 
    uint32_t <strong><span style="color: #000000">nBlock</span></strong>
);</pre></div></div>
<a name="507265636F6E646974696F6E73"></a><div class="Element14">
Preconditions</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
<a href="00355.html" target="topic">DRV_MEMORY_Open</a>() must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle.</p></div>
</div>
<a name="506172616D6574657273"></a><div class="Element14">
Parameters</div>
<div class="Element11">
<div class="Element10">
<div class="Element312">
<div class="TableDiv">
<table cellspacing="0" class="Table3">
<tr>
<td class="Element300" valign="top" width="35%">
<div class="Element301">
Parameters&nbsp;</div></td><td class="Element304" valign="top" width="65%">
<div class="Element305">
Description&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
handle&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
A valid open-instance handle, returned from the driver's open function<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
commandHandle&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Pointer to an argument that will contain the command handle<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
targetBuffer&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Buffer into which the data read from the media device memory will be placed<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
blockStart&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Block start from where the data should be read.<br>&nbsp;</div></td></tr><tr>
<td class="Element302" valign="top" width="35%">
<div class="Element303">
nBlock&nbsp;</div></td><td class="Element306" valign="top" width="65%">
<div class="Element307">
Total number of blocks to be read.&nbsp;</div></td></tr></table></div></div>
</div>
</div>
<a name="52657475726E73"></a><div class="Element14">
Returns</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
The command handle is returned in the commandHandle argument. It will be <a href="00307.html" target="topic">DRV_MEMORY_COMMAND_HANDLE_INVALID</a> if the request was not successful.</p></div>
</div>
<a name="52656D61726B73"></a><div class="Element14">
Remarks</div>
<div class="Element11">
<div class="Element10">
<p class="Element10">
None.</p></div>
</div>
<a name="4578616D706C65"></a><div class="Element14">
Example</div>
<div class="Element11">
<div class="Element10">
<div class="Element13"><div class="Element12"><pre class="Element12">
uint8_t readBuffer[BUFFER_SIZE];

<i><span style="color: #008000">// Use DRV_MEMORY_GeometryGet () to find the read region geometry.</span></i>
<i><span style="color: #008000">// Find the block address from which to read data.</span></i>
uint32_t blockStart = 0x0;
uint32_t nBlock = BUFFER_SIZE;
<a href="00306.html" target="topic">DRV_MEMORY_COMMAND_HANDLE</a> commandHandle;
<strong><span style="color: #000080">bool</span></strong> xfer_done = <strong><span style="color: #000080">false</span></strong>;

<i><span style="color: #008000">// memoryHandle is the handle returned by the DRV_MEMORY_Open function.</span></i>

 <i><span style="color: #008000">// Event is received when the write request is completed.</span></i>
<strong><span style="color: #000080">void</span></strong> appTransferHandler
(
    <a href="00335.html" target="topic">DRV_MEMORY_EVENT</a> event,
    <a href="00306.html" target="topic">DRV_MEMORY_COMMAND_HANDLE</a> commandHandle,
    uintptr_t context
)
{
    <strong><span style="color: #000080">switch</span></strong>(event)
    {
        <strong><span style="color: #000080">case</span></strong> DRV_MEMORY_EVENT_COMMAND_COMPLETE:
            xfer_done = <strong><span style="color: #000080">true</span></strong>;
            <strong><span style="color: #000080">break</span></strong>;
        <strong><span style="color: #000080">case</span></strong> DRV_MEMORY_EVENT_COMMAND_ERROR:
            <i><span style="color: #008000">// Handle Error</span></i>
            <strong><span style="color: #000080">break</span></strong>;
        <strong><span style="color: #000080">default</span></strong>:
            <strong><span style="color: #000080">break</span></strong>;
    }
}

<a href="00364.html" target="topic">DRV_MEMORY_TransferHandlerSet</a>(memoryHandle, appTransferHandler, (uintptr_t)NULL);

DRV_MEMORY_AsyncRead(memoryHandle, &amp;commandHandle, &amp;readBuffer, blockStart, nBlock);

<strong><span style="color: #000080">if</span></strong>(<a href="00307.html" target="topic">DRV_MEMORY_COMMAND_HANDLE_INVALID</a> == commandHandle)
{
    <i><span style="color: #008000">// Error handling here</span></i>
}

<strong><span style="color: #000080">while</span></strong>(!xfer_done);
</pre></div></div>
</div>
</div>
</div>
<!-- End Page Content -->

<!-- Begin Page Footer -->
<div class="Element95">
<a href="00007.html" target="topic">Driver Libraries Help</a> &gt; <a href="00071.html" target="topic">Memory Driver Library Help</a> &gt; <a href="00072.html" target="topic">Library Interface</a> &gt; c) Block Operation Functions &gt; <a href="00303.html" target="topic">DRV_MEMORY_AsyncRead Function</a></div>
<div class="Element93">
<table width="100%" cellspacing="0" cellpadding="0">
<tr><td width="25%">
<div class="Element3">
MPLAB Harmony Core Help</div>
</td><td width="25%">
<div class="Element4">
<a href="contents.html" target="tocidx">Contents</a> | <a href="00007.html" target="topic">Home</a></div>
</td><td width="25%">
<div class="Element91">
<a href="00302.html" target="topic">Previous</a> | <a href="00072.html" target="topic">Up</a> | <a href="00304.html" target="topic">Next</a></div>
</td><td width="25%">
<div class="Element97">
<a href="mailto:docerrors@microchip.com&subject=MPLAB Harmony Documentation Feedback (Topic ID: DRV_MEMORY_AsyncRead@DRV_HANDLE@DRV_MEMORY_COMMAND_HANDLE *@void *@uint32_t@uint32_t Topic Title: DRV_MEMORY_AsyncRead Function)&body=Thank you for your feedback! Please include a description of your feedback, and indicate whether you are reporting an an error in the documentation or an enhancement.">Documentation Feedback</a><br> <a href="http://support.microchip.com" target="_blank">Microchip Support</a></div>
</td></tr></table></div>

<!-- End Page Footer -->
</div>
</div>

<!-- End Client Area -->
</body></html>